/*
    * Copyright (C) 2011 The Guava Authors
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.apache.org/licenses/LICENSE-2.0
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package com.google.common.testing;
  
  import static java.util.concurrent.TimeUnit.SECONDS;
  
  import com.google.common.annotations.Beta;
  
  import java.lang.ref.WeakReference;
  import java.util.concurrent.CancellationException;
  import java.util.concurrent.CountDownLatch;
  import java.util.concurrent.ExecutionException;
  import java.util.concurrent.Future;
  import java.util.concurrent.TimeoutException;
  
  /**
   * Testing utilities relating to garbage collection finalization.
   *
   * <p>Use this class to test code triggered by <em>finalization</em>, that is, one of the
   * following actions taken by the java garbage collection system:
   *
   * <ul>
   * <li>invoking the {@code finalize} methods of unreachable objects
   * <li>clearing weak references to unreachable referents
   * <li>enqueuing weak references to unreachable referents in their reference queue
   * </ul>
   *
   * <p>This class uses (possibly repeated) invocations of {@link java.lang.System#gc()} to cause
   * finalization to happen.  However, a call to {@code System.gc()} is specified to be no more
   * than a hint, so this technique may fail at the whim of the JDK implementation, for example if
   * a user specified the JVM flag {@code -XX:+DisableExplicitGC}.  But in practice, it works very
   * well for ordinary tests.
   *
   * <p>Failure of the expected event to occur within an implementation-defined "reasonable" time
   * period or an interrupt while waiting for the expected event will result in a {@link
   * RuntimeException}.
   *
   * <p>Here's an example that tests a {@code finalize} method:
   *
   * <pre>   {@code
   *   final CountDownLatch latch = new CountDownLatch(1);
   *   Object x = new MyClass() {
   *     ...
   *     protected void finalize() { latch.countDown(); ... }
   *   };
   *   x = null;  // Hint to the JIT that x is stack-unreachable
   *   GcFinalization.await(latch);}</pre>
   *
   * <p>Here's an example that uses a user-defined finalization predicate:
   *
   * <pre>   {@code
   *   final WeakHashMap<Object, Object> map = new WeakHashMap<Object, Object>();
   *   map.put(new Object(), Boolean.TRUE);
   *   GcFinalization.awaitDone(new FinalizationPredicate() {
   *     public boolean isDone() {
   *       return map.isEmpty();
   *     }
   *   });}</pre>
   *
   * <p>Even if your non-test code does not use finalization, you can
   * use this class to test for leaks, by ensuring that objects are no
   * longer strongly referenced:
   *
   * <pre> {@code
   * // Helper function keeps victim stack-unreachable.
   * private WeakReference<Foo> fooWeakRef() {
   *   Foo x = ....;
   *   WeakReference<Foo> weakRef = new WeakReference<Foo>(x);
   *   // ... use x ...
   *   x = null;  // Hint to the JIT that x is stack-unreachable
   *   return weakRef;
   * }
   * public void testFooLeak() {
   *   GcFinalization.awaitClear(fooWeakRef());
   * }}</pre>
   *
   * <p>This class cannot currently be used to test soft references, since this class does not try to
   * create the memory pressure required to cause soft references to be cleared.
   *
   * <p>This class only provides testing utilities.  It is not designed for direct use in production
   * or for benchmarking.
   *
   * @author mike nonemacher
   * @author Martin Buchholz
   * @since 11.0
  */
 @Beta
 public final class GcFinalization {
   private GcFinalization() {}
 
   /**
    * 10 seconds ought to be long enough for any object to be GC'ed and finalized.  Unless we have a
    * gigantic heap, in which case we scale by heap size.
    */
   private static long timeoutSeconds() {
     // This class can make no hard guarantees.  The methods in this class are inherently flaky, but
     // we try hard to make them robust in practice.  We could additionally try to add in a system
     // load timeout multiplier.  Or we could try to use a CPU time bound instead of wall clock time
     // bound.  But these ideas are harder to implement.  We do not try to detect or handle a
     // user-specified -XX:+DisableExplicitGC.
     //
     // TODO(user): Consider using
     // java/lang/management/OperatingSystemMXBean.html#getSystemLoadAverage()
     //
     // TODO(user): Consider scaling by number of mutator threads,
     // e.g. using Thread#activeCount()
     return Math.max(10L, Runtime.getRuntime().totalMemory() / (32L * 1024L * 1024L));
   }
 
   /**
    * Waits until the given future {@linkplain Future#isDone is done}, invoking the garbage
    * collector as necessary to try to ensure that this will happen.
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    */
   public static void awaitDone(Future<?> future) {
     if (future.isDone()) {
       return;
     }
     final long timeoutSeconds = timeoutSeconds();
     final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
     do {
       System.runFinalization();
       if (future.isDone()) {
         return;
       }
       System.gc();
       try {
         future.get(1L, SECONDS);
         return;
       } catch (CancellationException ok) {
         return;
       } catch (ExecutionException ok) {
         return;
       } catch (InterruptedException ie) {
         throw new RuntimeException("Unexpected interrupt while waiting for future", ie);
       } catch (TimeoutException tryHarder) {
         /* OK */
       }
     } while (System.nanoTime() - deadline < 0);
     throw new RuntimeException(
         String.format("Future not done within %d second timeout", timeoutSeconds));
   }
 
   /**
    * Waits until the given latch has {@linkplain CountDownLatch#countDown counted down} to zero,
    * invoking the garbage collector as necessary to try to ensure that this will happen.
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    */
   public static void await(CountDownLatch latch) {
     if (latch.getCount() == 0) {
       return;
     }
     final long timeoutSeconds = timeoutSeconds();
     final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
     do {
       System.runFinalization();
       if (latch.getCount() == 0) {
         return;
       }
       System.gc();
       try {
         if (latch.await(1L, SECONDS)) {
           return;
         }
       } catch (InterruptedException ie) {
         throw new RuntimeException("Unexpected interrupt while waiting for latch", ie);
       }
     } while (System.nanoTime() - deadline < 0);
     throw new RuntimeException(
         String.format("Latch failed to count down within %d second timeout", timeoutSeconds));
   }
 
   /**
    * Creates a garbage object that counts down the latch in its finalizer.  Sequestered into a
    * separate method to make it somewhat more likely to be unreachable.
    */
   private static void createUnreachableLatchFinalizer(final CountDownLatch latch) {
     new Object() { @Override protected void finalize() { latch.countDown(); }};
   }
 
   /**
    * A predicate that is expected to return true subsequent to <em>finalization</em>, that is, one
    * of the following actions taken by the garbage collector when performing a full collection in
    * response to {@link System#gc()}:
    *
    * <ul>
    * <li>invoking the {@code finalize} methods of unreachable objects
    * <li>clearing weak references to unreachable referents
    * <li>enqueuing weak references to unreachable referents in their reference queue
    * </ul>
    */
   public interface FinalizationPredicate {
     boolean isDone();
   }
 
   /**
    * Waits until the given predicate returns true, invoking the garbage collector as necessary to
    * try to ensure that this will happen.
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    */
   public static void awaitDone(FinalizationPredicate predicate) {
     if (predicate.isDone()) {
       return;
     }
     final long timeoutSeconds = timeoutSeconds();
     final long deadline = System.nanoTime() + SECONDS.toNanos(timeoutSeconds);
     do {
       System.runFinalization();
       if (predicate.isDone()) {
         return;
       }
       CountDownLatch done = new CountDownLatch(1);
       createUnreachableLatchFinalizer(done);
       await(done);
       if (predicate.isDone()) {
         return;
       }
     } while (System.nanoTime() - deadline < 0);
     throw new RuntimeException(
         String.format("Predicate did not become true within %d second timeout", timeoutSeconds));
   }
 
   /**
    * Waits until the given weak reference is cleared, invoking the garbage collector as necessary
    * to try to ensure that this will happen.
    *
    * <p>This is a convenience method, equivalent to:
    * <pre>   {@code
    *   awaitDone(new FinalizationPredicate() {
    *     public boolean isDone() {
    *       return ref.get() == null;
    *     }
    *   });}</pre>
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    */
   public static void awaitClear(final WeakReference<?> ref) {
     awaitDone(new FinalizationPredicate() {
       public boolean isDone() {
         return ref.get() == null;
       }
     });
   }
 
   /**
    * Tries to perform a "full" garbage collection cycle (including processing of weak references
    * and invocation of finalize methods) and waits for it to complete.  Ensures that at least one
    * weak reference has been cleared and one {@code finalize} method has been run before this
    * method returns.  This method may be useful when testing the garbage collection mechanism
    * itself, or inhibiting a spontaneous GC initiation in subsequent code.
    *
    * <p>In contrast, a plain call to {@link java.lang.System#gc()} does not ensure finalization
    * processing and may run concurrently, for example, if the JVM flag {@code
    * -XX:+ExplicitGCInvokesConcurrent} is used.
    *
    * <p>Whenever possible, it is preferable to test directly for some observable change resulting
    * from GC, as with {@link #awaitClear}.  Because there are no guarantees for the order of GC
    * finalization processing, there may still be some unfinished work for the GC to do after this
    * method returns.
    *
    * <p>This method does not create any memory pressure as would be required to cause soft
    * references to be processed.
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    * @since 12.0
    */
   public static void awaitFullGc() {
     final CountDownLatch finalizerRan = new CountDownLatch(1);
     WeakReference<Object> ref = new WeakReference<Object>(
         new Object() {
           @Override protected void finalize() { finalizerRan.countDown(); }
         });
 
     await(finalizerRan);
     awaitClear(ref);
 
     // Hope to catch some stragglers queued up behind our finalizable object
     System.runFinalization();
   }
 }